---
title: Operational runbook
summary: Deployment, health checks, logs, status codes, error scenarios, and recovery procedures for PdfAPI.
status: draft
owner: Not determined from source
last_reviewed: 2026-09-17
library: PdfAPI
reference_type: embedded
---

# Operational runbook

PdfAPI is an IIS-hosted ASP.NET Web API 2 service with no in-code authorization, three coexisting error-handling mechanisms, and a single Oracle-backed tracking dependency. This runbook records deployment, health, status-code, logging, error-scenario, and monitoring findings as observed in source and pipeline configuration.

## Deployment

| Attribute | Value |
| --- | --- |
| Host | IIS |
| Site / virtual directory | Not determined from source** |
| Application pool | Not determined from source** |
| Deployment mechanism | Azure Pipelines — `Pipelines\build-vars.yml` (`AppType: api`) |
| Artifact | Deployed to IIS, not packaged as a NuGet artifact — see [Dependencies: Produced packages](dependencies.md#produced-packages) for the two packages produced from this repository (`PdfAPI.Client`, `Pdf.Local.Client`), neither of which is the deployed API application itself |

## Environments

| Environment | Base address | Environment track | Notes |
| --- | --- | --- | --- |
| DEV | Not determined from source** | `entdev01` (`ApplicationHost` committed in `Web.config`) | Development host name committed to source control with no active transform override — see [Tech debt](tech-debt.md) |
| TEST | Not determined from source** | `enttest03` (observed in `PdfAPI.Tests\App.config`) | Sibling-project evidence only; not asserted as the live TEST value for the deployed API |
| PROD | Not determined from source** | `netprod` (observed in `PdfApiClientTester\PdfApiClientTester\App.config`) | Sibling-project evidence only; not asserted as the live PROD value for the deployed API |

## Health verification

| Check | Request | Expected result |
| --- | --- | --- |
| Service responds | `GET buildVersion` | `200 OK` with build metadata key/value pairs — no dedicated health-check endpoint exists in this service, so this is the lightest read operators can safely call |
| API documentation surface reachable | `GET /swagger/ui/index` (Swagger UI, default route) | `200 OK` with the Swagger UI page — Swagger is live via `PreApplicationStartMethod` in `SwaggerConfig.cs` |

## Status codes

| Code | Meaning | Operator action |
| --- | --- | --- |
| `200 OK` | Success, **and** every processing failure on `POST v1/convert`, `POST v1/convert/{fileExtension}`, `POST v1/extract`, `POST v1/merge`, and `GET v1/legacy/download/{trackingId}` — inspect `PdfResult.Status`/`Message` in the body, not the HTTP status, for these five endpoints | None for a true success; inspect body for a failure `PdfResult` |
| `500 Internal Server Error` | Unhandled exception on any of the eight endpoints with no `try`/`catch` (`InfoController`'s seven actions, `ApiInfoController`'s one action) — the framework produces exception detail (`IncludeErrorDetailPolicy.Always`) before `ApiResponseHandler` runs; the final client-visible envelope is unknown** (see [Endpoints: Error response shape](endpoints.md#error-response-shape)) | Escalate with the logged exception detail; treat any exception detail reaching operators as sensitive and avoid forwarding it externally |
| `404 Not Found` | Route does not match — e.g. a non-numeric `{trackingId}` segment, produced by the framework's routing | Verify the route and the identifier supplied by the caller |

## Logs

| Surface | Location | Content | Retention |
| --- | --- | --- | --- |
| `ILogService.LogException` / `TraceError` / `TraceWarn` / `TraceDebug` | Not determined from source** — backend implementation is supplied by the SAIF framework and configured outside this repository | Exception details from `ConvertController`, `ExtractController`, `MergeController`, `LegacyController`, `ActivePdfService`, `PdfService.SendIncidentEmail` | Not determined from source** |
| `log4net 2.0.5` | Not determined from source** | Referenced in `packages.config`; no `log4net.config` appender configuration is present in this repository | Not determined from source** |
| Stray console output | Process standard output (IIS-hosted; not surfaced to a log file by this repository) | `Console.WriteLine(result.ToString())` at the end of `SyncfusionPdfService.FinalizeResult` — see [Tech debt](tech-debt.md) | Not applicable |

## Environment configuration

| Setting | Key | Purpose |
| --- | --- | --- |
| Processor selector | `pdfapi.pdfservicetype` | Selects ActivePDF vs Syncfusion processor |
| Working directory | `pdfapi.rootdirectory` | Filesystem root for conversion working/output files |
| Temp-save toggle | `pdfapi.saveInputToTemp` | Enables writing inbound documents to temp storage |
| Failure notification sender | `noreplyemailsenderaddress` | From-address for incident emails |
| Failure notification recipient | `pdfapi.ErrorEmail.Recipient` | To-address for incident emails |
| ActivePDF retry codes | `pdfApi.ErrorsToRetry` | CSV of vendor error codes that trigger an ActivePDF retry |

See [Configuration](configuration.md) for the complete settings catalog, including the runtime resolution of the database connection.

## Error scenarios

| Scenario | Symptom | Impact | Recovery |
| --- | --- | --- | --- |
| Environment API unavailable | Failure during dependency registration or first configuration read (e.g. `pdfapi.rootdirectory` read in the `PdfService` base constructor) | Requests fail at DI resolution time; the affected controller cannot be constructed | Verify Environment API availability for the configured `ApplicationHost` track |
| Oracle connection resolution fails | Exception from `DbConnectionManager.GetOracleConnectionString` or the underlying NHibernate session | All tracking-dependent endpoints fail; non-tracking `v1/info/*` endpoints continue to function | Verify the `EnvironmentConfigKeys.OracleDatabase` environment key and the hard-coded `"IMG"` schema argument, then confirm Oracle availability |
| `pdfApi.ErrorsToRetry` misconfigured | `FormatException` from `long.Parse` during `ActivePdfService` construction (unguarded parse) | Every request routed to the ActivePDF processor fails at construction | Correct the CSV value in the Environment API configuration for `pdfApi.ErrorsToRetry` |
| SMTP host unreachable | Incident email send fails silently or throws inside `SendIncidentEmail` | Failure notifications are not delivered; the triggering request's own result is unaffected* | Verify connectivity to the hard-coded `mail.saif.com` host |
| Application pool recycled under load | Intermittent request failures; in-flight tracking rows may be left in `PROC` with no terminal update | Tracked requests may appear permanently `Processing` to polling clients | Investigate via `GET v1/info/track/{trackingId}`; manually reconcile stuck tracking rows if the external persistence tooling allows |

## Monitoring and alerting

**No telemetry or alerting is configured.** A grep for `ConfigureOpenTelemetry(` across `PdfAPI`, `PdfAPI.Core`, and `PdfApi.SyncFusionCore` returned zero matches, and no Application Insights, OpenTelemetry, or metrics package appears in `PdfAPI\packages.config`. The only observability in force is logging through `ILogService` and `log4net`. No alert rules are defined in this repository.

## Related documentation
- [API index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Endpoints](endpoints.md)
- [Authentication and authorization](authentication-authorization.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Data model](data-model.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with `**` could not be confirmed; treat as unknown until verified.

## Sources
- PdfAPI\Global.asax.cs
- PdfAPI\App_Start\WebApiConfig.cs
- PdfAPI\App_Start\SwaggerConfig.cs
- PdfAPI\Controllers\v1\ApiInfoController.cs
- PdfAPI\Services\ActivePdf\ActivePdfService.cs
- PdfAPI\Services\PdfService.cs
- Pipelines\build-vars.yml
- PdfAPI\Web.config
- PdfAPI.Tests\App.config
- PdfApiClientTester\PdfApiClientTester\App.config